Agora Objective-C API Overview

声网通过全球部署的虚拟网络，提供可以灵活搭配的 API 组合，为移动端到移动端以及移动端到 Web 端提供质量可靠的实时音视频通信。

AgoraRtcEngineKit 是 Agora SDK 的入口类，提供所有可供 App 调用的方法。
AgoraRtcEngineDelegate 接口类采用 Delegate 方法向 App 发送回调通知。
AgoraRtcChannel 类在指定频道中实现实时音视频功能。通过创建多个 AgoraRtcChannel 对象，用户可以同时加入多个频道。
AgoraRtcChannelDelegate 类监听和报告指定频道的事件和数据。

自 v2.3.3 开始，Agora Objective-C API Reference for iOS/macOS 可以在 Dash 下载，详见 FAQ。

频道管理

方法	功能
sharedEngineWithAppId	初始化引擎
destroy	销毁 RtcEngine 实例
setChannelProfile	设置频道场景
setClientRole	设置直播场景的用户角色
joinChannelByToken	加入频道
switchChannelByToken	快速切换直播频道
leaveChannel	离开频道
renewToken	更新 Token
getConnectionState	获取网络连接状态

频道事件

事件	描述
didJoinChannel	已加入频道
didRejoinChannel	已重新加入频道
didLeaveChannelWithStats	已离开频道
didClientRoleChanged	用户角色已切换
didJoinedOfUid	远端用户已加入频道
didOfflineOfUid	远端用户已离开频道
connectionChangedToState	网络连接状态已改变
networkTypeChangedToType	本地网络类型发生改变
rtcEngineConnectionDidLost	网络连接中断且 SDK 无法在 10 秒内连接服务器
tokenPrivilegeWillExpire	Token 服务即将过期
rtcEngineRequestToken	Token 已过期

音频管理

方法	功能
enableAudio	启用音频模块
disableAudio	关闭音频模块
setAudioProfile	设置音频编码配置
adjustRecordingSignalVolume	调节录音音量
adjustUserPlaybackSignalVolume	调节本地播放的指定远端用户音量。
adjustPlaybackSignalVolume	调节本地播放的所有远端用户音量。
enableLocalAudio	开关本地音频采集
muteLocalAudioStream	开关本地音频发送
muteRemoteAudioStream	停止/恢复接收指定音频流
muteAllRemoteAudioStreams	停止/恢复接收所有音频流
setDefaultMuteAllRemoteAudioStreams	设置是否默认接收音频流

视频管理

方法	功能
enableVideo	启用视频模块
disableVideo	关闭视频模块
setVideoEncoderConfiguration	设置视频编码配置
setupLocalVideo	初始化本地用户视图
setupRemoteVideo	初始化远端用户视图
setLocalRenderMode	更新本地视图显示模式
setRemoteRenderMode	更新远端视图显示模式
startPreview	开启视频预览
stopPreview	停止视频预览
enableLocalVideo	开关本地视频采集
muteLocalVideoStream	开关本地视频发送
muteRemoteVideoStream	停止/恢复接收指定视频流
muteAllRemoteVideoStreams	停止/恢复接收所有视频流
setDefaultMuteAllRemoteVideoStreams	设置是否默认接收视频流

本地媒体事件

事件	描述
localAudioStateChange	本地音频状态发生改变
localVideoStateChange	本地视频状态发生改变
firstLocalAudioFrame	已发送本地音频首帧
firstLocalVideoFrameWithSize	已显示本地视频首帧

远端媒体事件

事件	描述
remoteAudioStateChangedOfUid	远端音频流状态发生改变
remoteVideoStateChangedOfUid	远端用户视频流状态发生改变

数据统计事件

加入频道后，SDK 每隔 2 秒自动触发本组回调。

我们为这些回调提供了详细的功能描述、实现方法文档，详情请参考《通话中质量监测》。

事件	描述
remoteAudioStats	报告通话中远端音频流的统计信息
reportRtcStats	报告 Rtc Engine 统计信息
networkQuality	报告网络上下行质量
localAudioStats	通话中本地音频流的统计信息回调
localVideoStats	报告本地视频统计信息
remoteVideoStats	报告远端视频统计信息

视频前处理及后处理

方法	功能
setBeautyEffectOptions	设置美颜效果选项（仅 iOS）

多频道管理

我们为该组 API 提供了详细的场景描述、实现方法及开发注意事项文档，详情请参考《加入多频道》。

API	功能
createRtcChannel	创建并获取一个 AgoraRtcChannel 对象。通过创建多个对象，用户可以同时加入多个频道。
AgoraRtcChannel	该类提供在指定频道内实现实时音视频功能的方法。
AgoraRtcChannelDelegate	该类提供监听指定频道事件和数据的回调。

屏幕共享

我们为该组接口提供了详细的场景描述、实现方法及开发注意事项文档，详情请参考《屏幕共享》。

本组方法仅适用于macOS，不适用于 iOS。

方法	功能
startScreenCaptureByDisplayId	通过屏幕 ID 共享屏幕
startScreenCaptureByWindowId	通过窗口 ID 共享窗口
setScreenCaptureContentHint	设置屏幕共享内容类型
updateScreenCaptureParameters	更新屏幕共享的编码参数配置
updateScreenCaptureRegion	更新屏幕共享区域
stopScreenCapture	停止屏幕共享

音乐文件播放及混音

方法	功能
startAudioMixing	开始播放音乐文件
stopAudioMixing	停止播放音乐文件
pauseAudioMixing	暂停播放音乐文件
resumeAudioMixing	恢复播放音乐文件
adjustAudioMixingVolume	调节音乐文件播放音量
adjustAudioMixingPlayoutVolume	调节音乐文件的本地播放音量
adjustAudioMixingPublishVolume	调节音乐文件的远端播放音量
getAudioMixingPlayoutVolume	获取音乐文件的本地播放音量
getAudioMixingPublishVolume	获取音乐文件的远端播放音量
getAudioMixingDuration	获取音乐文件播放时长
getAudioMixingCurrentPosition	获取音乐文件播放进度
setAudioMixingPosition	设置音乐文件的播放位置

事件	描述
localAudioMixingStateDidChanged	本地音乐文件播放状态改变
rtcEngineRemoteAudioMixingDidStart	远端音乐文件播放已开始
rtcEngineRemoteAudioMixingDidFinish	远端音乐文件播放已结束

音效文件播放管理

方法	功能
getEffectsVolume	获取音效文件播放音量
setEffectsVolume	设置音效文件播放音量
setVolumeOfEffect	实时调整音效文件播放音量
playEffect	播放指定音效文件
stopEffect	停止播放指定音效文件
stopAllEffects	停止播放所有音效文件
preloadEffect	将指定音效文件预加载至内存
unloadEffect	从内存释放某个预加载的音效文件
pauseEffect	暂停音效文件播放
pauseAllEffects	暂停所有音效文件播放
resumeEffect	恢复播放指定音效文件
resumeAllEffects	恢复播放所有音效文件

事件	描述
rtcEngineDidAudioEffectFinish	本地音效文件播放已结束

变声与混响

方法	功能
setLocalVoicePitch	设置本地语音音调
setLocalVoiceEqualizationOfBandFrequency	设置本地语音音效均衡
setLocalVoiceReverbOfType	设置本地音效混响
setLocalVoiceChanger	设置本地语音变声
setLocalVoiceReverbPreset	设置预设的本地语音混响效果

听声辨位

方法	功能
enableSoundPositionIndication	开启/关闭远端用户的语音立体声
setRemoteVoicePosition	设置远端用户的语音位置

CDN 推流

本组方法仅适用于直播场景。

方法	功能
setLiveTranscoding	设置直播转码
addPublishStreamUrl	增加旁路推流地址
removePublishStreamUrl	删除旁路推流地址

事件	描述
rtmpStreamingChangedToState	RTMP 推流状态发生改变
rtcEngineTranscodingUpdated	旁路推流设置已被更新

跨频道媒体流转发

方法	功能
startChannelMediaRelay	开始跨频道媒体流转发
updateChannelMediaRelay	更新媒体流转发的频道
stopChannelMediaRelay	停止跨频道媒体流转发

事件	描述
channelMediaRelayStateDidChange	跨频道媒体流转发状态发生改变
didReceiveChannelMediaRelayEvent	跨频道媒体流转发事件

音量提示

方法	功能
enableAudioVolumeIndication	启用说话者音量提示

事件	描述
reportAudioVolumeIndicationOfSpeakers	提示频道内谁在说话以及说话者的音量
activeSpeaker	监测到活跃用户

音频播放路由

本组方法仅适用于 iOS，不适用于 macOS。

方法	功能
setDefaultAudioRouteToSpeakerphone	设置默认的音频播放路由
setEnableSpeakerphone	启用/关闭扬声器播放
isSpeakerphoneEnabled	查询扬声器启用状态

事件	描述
didAudioRouteChanged	语音路由已改变

耳返控制

本组方法仅适用于 iOS，不适用于 macOS。

方法	功能
enableInEarMonitoring	开启耳返功能
setInEarMonitoringVolume	设置耳返音量

视频双流模式

方法	功能
enableDualStreamMode	开关视频双流模式
setRemoteVideoStream	设置订阅的视频流类型
setRemoteDefaultVideoStreamType	设置默认订阅的视频流类型

音视频流回退

我们为该组接口提供了详细的场景描述、实现方法及开发注意事项文档，详情请参考《视频流回退》。

方法	功能
setRemoteUserPriority	设置远端用户流的优先级
setLocalPublishFallbackOption	设置弱网条件下发布的音视频流回退选项
setRemoteSubscribeFallbackOption	设置弱网条件下订阅的音视频流回退选项

事件	描述
didLocalPublishFallbackToAudioOnly	本地发布流已回退为音频流或恢复为音视频流
didRemoteSubscribeFallbackToAudioOnly	远端订阅流已回退为音频流或恢复为音视频流

通话前网络测试

我们为该组接口提供了详细的场景描述、实现方法及开发注意事项文档，详情请参考《通话前检测网络质量》。

方法	功能
startEchoTestWithInterval	开始语音通话回路测试
stopEchoTest	停止语音通话回路测试
enableLastmileTest	启用网络测试
disableLastmileTest	关闭网络测试
startLastmileProbeTest	开始通话前网络质量探测
stopLastmileProbeTest	停止通话前网络质量探测

事件	描述
lastmileQuality	报告本地用户的网络质量
lastmileProbeTestResult	报告通话前网络上下行 last mile 质量

自定义视频模块

方法	功能
setVideoSource	设置自定义视频源
setLocalVideoRenderer	设置本地自定义视频渲染器
setRemoteVideoRenderer	设置远端自定义视频渲染器
videoSource	获取当前视频源
localVideoRenderer	获取本地视频渲染器
remoteVideoRendererOfUserId	获取远端视频渲染器

音频自采集（仅适用于 Push 模式）

方法	功能
enableExternalAudioSourceWithSampleRate	开启外部音频采集
disableExternalAudioSource	关闭外部音频采集
pushExternalAudioFrameRawData	推送外部原始音频帧
pushExternalAudioFrameSampleBuffer	推送外部 CMSampleBuffer 音频帧

音频自渲染

方法	功能
enableExternalAudioSink	开启外部音频渲染
disableExternalAudioSink	关闭外部音频渲染
pullPlaybackAudioFrameRawData	拉取 RawData 格式的远端音频数据
pullPlaybackAudioFrameSampleBufferByLengthInByte	拉取 SampleBuffer 格式的远端音频数据

视频自采集（仅适用于 Push 模式）

方法	功能
setExternalVideoSource	配置外部视频源
pushExternalVideoFrame	推送外部视频帧

原始音频数据

你可以使用 C++ 的原始音频数据接口实现相关功能，详见 C++ 原始音频数据。

方法	功能
setRecordingAudioFrameParametersWithSampleRate	设置录制的声音格式
setPlaybackAudioFrameParametersWithSampleRate	设置播放的声音格式
setMixedAudioFrameParametersWithSampleRate	设置录制和播放声音混音后的数据格式

原始视频数据

你可以使用 C++ 的原始视频数据接口实现相关功能，详见 C++ 原始视频数据。

媒体附属信息

本组方法仅适用于直播场景。

请不要在 AgoraRtcEngineDelegate 中实现 metadataMaxSize、readyToSendMetadataAtTimestamp 和 receiveMetadata 回调。

方法	功能
setMediaMetadataDataSource	设置媒体附属信息的 Data source
setMediaMetadataDataDelegate	设置媒体附属信息的 Delegate

事件	描述
metadataMaxSize	请求媒体附属信息的最大数据大小
readyToSendMetadataAtTimestamp	发送端已准备好发送媒体附属信息
receiveMetadata	接收端已收到媒体附属信息

直播视频水印

本组方法仅适用于直播场景。

方法	功能
addVideoWatermark	添加本地视频水印
clearVideoWatermarks	删除已添加的视频水印

加密

方法	功能
setEncryptionSecret	启用内置加密，并设置数据加密密钥
setEncryptionMode	设置内置的加密方案

音频录制

方法	功能
startAudioRecording	开始客户端录音
stopAudioRecording	停止客户端录音

直播输入在线媒体流

本组方法仅适用于直播场景。

我们为该组接口提供了详细的场景描述、实现方法及开发注意事项文档，详情请参考《输入在线媒体流》。

方法	功能
addInjectStreamUrl	输入在线媒体流 URL
removeInjectStreamUrl	删除输入的在线媒体流

事件	描述
streamInjectedStatusOfUrl	输入在线媒体流状态

摄像头控制

本组方法仅适用于 iOS，不适用于 macOS。

方法	功能
switchCamera	切换前置/后置摄像头
isCameraZoomSupported	检测设备是否支持摄像头缩放功能
isCameraTorchSupported	检测设备是否支持闪光灯常开
isCameraFocusPositionInPreviewSupported	检测设备是否支持手动对焦功能
isCameraExposurePositionSupported	检测设备是否支持手动曝光功能
isCameraAutoFocusFaceModeSupported	检测设备是否支持人脸对焦功能
setCameraZoomFactor	设置摄像头缩放比例
setCameraFocusPositionInPreview	设置手动对焦位置，并触发对焦
setCameraExposurePosition	设置手动曝光位置
setCameraTorchOn	设置是否打开闪光灯
setCameraAutoFocusFaceModeEnabled	设置是否开启人脸对焦功能

事件	描述
cameraFocusDidChangedToRect	摄像头对焦区域已改变
cameraExposureDidChangedToRect	摄像头曝光区域已改变

设备管理

本组方法仅适用于 macOS，不适用于 iOS。

方法	功能
monitorDeviceChange	监控设备改变
enumerateDevices	获取系统中所有的音视频设备
getDeviceInfo	获取当前设备名称
setDevice	指定设备
getDeviceVolume	获取设备音量
setDeviceVolume	设置设备音量
startRecordingDeviceTest	启动麦克风测试
stopRecordingDeviceTest	停止麦克风测试
startPlaybackDeviceTest	启动播放设备测试
stopPlaybackDeviceTest	停止播放设备测试
startCaptureDeviceTest	启动视频采集设备测试
stopCaptureDeviceTest	停止视频采集设备测试
startAudioDeviceLoopbackTest	开始音频设备回路测试
stopAudioDeviceLoopbackTest	停止音频设备回路测试

事件	描述
stateChanged	设备状态改变（仅适用于 macOS）

流消息

方法	功能
createDataStream	创建数据流
sendStreamMessage	发送数据流

事件	描述
receiveStreamMessageFromUid	接收到对方数据流消息
didOccurStreamMessageErrorFromUid	接收对方数据流消息发生错误

其他音频控制

方法	功能
enableLoopbackRecording	开启声卡采集（仅 macOS）
setAudioSessionOperationRestriction	设置 SDK 对 Audio Session 的控制权限（仅 iOS）

其他视频控制

方法	功能
setCameraCapturerConfiguration	设置摄像头采集偏好

其他方法

方法	功能
getCallId	获取通话 ID
rate	给通话评分
complain	投诉通话质量
enableMainQueueDispatch	分发／不分发回调至主队列
getSdkVersion	查询 SDK 版本号
getErrorDescription	获取警告或错误描述
setLogFile	设置日志文件
setLogFileSize	设置日志文件大小
setLogFilter	设置日志输出等级
getNativeHandle	获取 SDK 引擎的 C++ 句柄
delegate	设置/获取回调事件

其他事件

事件	事件
didOccurWarning	发生警告
didOccurError	发生错误
didApiCallExecute	API 方法已执行

定制方法 (Technical Preview)

方法	功能
setParameters	通过 JSON 配置 SDK 提供技术预览或特别定制功能
getParameter	获取 Agora SDK 可供自定义的参数